Skip to content

docs: re-baseline the SDK contract to dsh 0.2.2-rc.1 - #28

Merged
btspoony merged 8 commits into
mainfrom
upgrade/13-dsh-0.2.2-rc1-adaptation
Nov 6, 2026
Merged

btspoony merged 8 commits into
mainfrom
upgrade/13-dsh-0.2.2-rc1-adaptation

Conversation

@btspoony

@btspoony btspoony commented Nov 6, 2026

Copy link
Copy Markdown
Member

Summary

Re-baselines the crate's verified-runtime contract from @deepseek-ai/[email protected] to dsh-v0.2.2-rc.1 and moves the CI keyless-handshake pin.

The audit conclusion that drove this change: the crate's implementation is already wire-compatible with 0.2.2-rc.1 and needs no code change. Upstream kept every request method and parameter the crate sends, session/prompt still enqueues verbatim, the four modelled notifications keep their payloads, SESSION_FORMAT_VERSION stays 4, and ContentBlockMap keeps its seven members. What did change is the documented baseline and two documented behaviors, plus the crate's own re-verification rule ("if upstream advances past the pinned ref, re-run the greps before restating any line").

What changed

  • Both frozen specs re-baselined (wire-parity-surface, runtime-launch-contract): eight declared request methods with the crate still sending six; six declared notifications with four modelled; session/query / approval/request / user-question/ask recorded as decided non-goals; subagent.started narrowed to subagent-origin sessions; resumed sessions take the initialized model route; new §7.7 records the run() routing divergence; earlier citation tables preserved append-only.
  • CI pin moved at all three sites to 0.2.2-rc.1. The resolve step now also asserts the resolved binary lives under $(npm prefix -g)/bin, so a preinstalled dsh earlier on PATH cannot satisfy the guard.
  • Source docs corrected (comments only, no logic): resume route override in src/api.rs; origin gate in src/client/session_tree.rs / src/client/core.rs.
  • README pair corrected in parity: the TypeScript RunResult.finishReason fact, the leading-/ prompt semantics, the opt-in client-directed request qualification, and the runtime Node >= 24.9.0 floor. README.i18n.yaml re-recorded.
  • Changelog fragment added (.changes/unreleased/dsh-0.2.2-rc1-realignment.md).
  • Knowledge guidance extended with the additive-wire-vs-behavioral-parity distinction and the pinned-install guard.

Verification

  • cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo build --all-targets && cargo test — 197 tests passed, 0 failed.
  • Upstream inventory re-run at tag 66491b05e3: 29 wire rows (27 PASS / 2 FAIL-fact) + 22 launch rows (20 PASS / 2 FAIL-moved); Changed rules: none.
  • Plan QC tri-review: 3 × Approve after targeted re-validation; 0 Critical / 0 Warning / 0 open Suggestion.
  • README.i18n.yaml blob hashes match git hash-object on both sides.

Non-goals

No new request method, notification parser, public API, dependency, or runtime behavior. The three unwrapped upstream capabilities are recorded as deliberate decisions, not gaps.

…rc.1

Restate both frozen specs from the T1 re-verification at
dsh-v0.2.2-rc.1 (66491b05e3), keeping every earlier table and dated
amendment as history.

Wire spec: eight upstream request methods and six notifications, with
the crate still sending exactly six and a session/query row marked
NOT sent; the two new notification names and the subagent.started
origin narrowing; fact corrections for the seven turn/end kinds,
Python run() -> session/query, TypeScript finishReason, and the
additive optional config fields; new section 7.7 for the session/prompt
divergence; decided non-goals for session/query, approval/request, and
user-question/ask; new re-baseline table and re-verification anchor.

Launch spec: re-anchor section 2.1 to the shipped-profile registry and
the first-use self-init, re-anchor initialize.cwd consumption, record
the Node >=24.9.0 install bound, and add the new re-baseline table and
re-verification anchor.
…e facts

CI: move the keyless-runtime-handshake pin to
@deepseek-ai/[email protected] at all three textual sites (npm cache key,
install command, fail-loud message) and rewrite the rationale for tag
dsh-v0.2.2-rc.1 (66491b05e3, 2026-11-04): eight upstream request
methods with the crate still sending six, six notifications with four
modelled, session/query, approval/request, and user-question/ask
deliberately unwrapped, and session.event.event still an untyped Value.
The setup-node step notes the runtime's >=24.9.0 floor; no Node major
bump was needed.

Rustdoc: session/resume records that the initialized route replaces
the restored session's stored model selection and that a stored
reasoning effort survives only on a matching provider and model
(server.ts:574-590 at the tag). The session-tree module and the
subscription doc record that subagent.started is emitted only for
subagent-origin sessions, so an ordinary fork adds no edge.

README pair: replace the false "four server-to-client notifications"
claim with the six-declared/four-modelled statement, name the two
unmodelled notifications and the subagent-origin emission rule in both
languages, and re-record both blob hashes in README.i18n.yaml.
…rgence

Fix the six consolidated plan-QC findings on the docs surfaces only:

- README pair: TypeScript's RunResult does carry the field, camelCase-named
  `finishReason: string | null`; the crate still follows Python's snake_case
  five-field set.
- README pair + `Session::run` rustdoc: the run step sequence follows Python
  but the crate posts `session/prompt`, so a leading `/` is prompt text and
  `session.query.completed` is never consumed (wire spec §7.7).
- README pair: bring-your-own runtime Node floor `>= 24.9.0` (npm CLI only;
  the wheel carries its own Node) with the upstream citation.
- Wire §6.1/§7.2: the runtime emits client-directed requests only to a client
  that opts in at `initialize`; this crate never opts in and answers `-32601`.
- Wire §6.1 and launch §6.1: split the additive-option paragraph so
  `reasoningEffort`/`maxTokens` are the already-supported `initialize` fields,
  and only the question/approval options gate the §8 non-goals.

README.i18n.yaml re-recorded from `git hash-object README.md README.zh.md`.
@wood-s-inspector

wood-s-inspector Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

✅ Verdict: ship it · Score 69% (pass)

Findings Count
🔴 must-fix 0
🟠 should-fix 0
🟡 may-fix 4
🔵 nit 2
❓ unverified 10

📋 Review

Findings

🟡 New verified-versions table contradicts the crate's current release notes about which runtime CI verifies

  • Evidence:
    • Evidence: README.md:70 — new row asserts 0.2.2-rc.1 is verified by "CI keyless handshake"; .github/workflows/ci.yml:103 does pin @deepseek-ai/[email protected], so the README row is correct. But CHANGELOG.md:8 (the newest release section's ### Changed bullet) still tells consumers "The CI keyless-runtime-handshake job now verifies the npm route against @deepseek-ai/[email protected]". A reader taking either artifact gets a different answer for the same gate.
    • Impact: The README change establishes a consumer-facing claim about what CI verifies, but the shipped release notes for the same release state a different runtime pin. One of the two artifacts lies to consumers; without the fix, the contradiction ships in the same release tarball (both README.md and CHANGELOG.md are package-included).
    • Effort: XS — one bullet line in CHANGELOG.md (or its unreleased fragment path) re-pinned to 0.2.2-rc.1.
    • Risk: LOW — prose only; no code or gates touched, and ci.yml:103 is the already-verified source of truth.
    • Confidence: HIGH (opened README.md:61-85, CHANGELOG.md:8, ci.yml:99-119).
    • Merge class: may-fix (documentation surface — capped here regardless of impact; the prose content is wrong on the CHANGELOG side and the README is the artifact that exposes it).
    • Fix sketch: Re-pin the CHANGELOG bullet (or the dsh-0.2.2-rc1-realignment fragment) to 0.2.2-rc.1 so the release notes and this new table agree; no README text change needed.
  • Location: README.md:61-85
  • Category: DOCS
  • Merge class: may-fix

🟡 Table asserts keyless-handshake verification for 0.2.1-rc.2–rc.5 that no repo artifact records

  • Evidence:
    • Evidence: README.md:63-64 — the section definition promises "Each release below was checked two ways: a keyless handshake … and a reading of the upstream SDK-facing surface at the release tag". README.md:71-74 — rows for 0.2.1-rc.5, rc.4, rc.3, rc.2 are marked verified for that handshake. A repo-wide search for those versions yields hits only in README.md/README.zh.md: no CI job exercises them (ci.yml:103 pins only 0.2.2-rc.1), no .mstar/specs/ or .mstar/knowledge/ record rebaselines at dsh-v0.2.1-rc.2…rc.5, and the changelog/fragments mention only 0.2.1-rc.1 and 0.2.2-rc.1 (.changes/unreleased/dsh-runtime-baseline-0.2.1-rc.1.md:4).
    • Impact: Four of the six rows state a completed two-stage verification whose evidence exists nowhere in the repository, so a consumer cannot reproduce or audit the claim — exactly the failure mode the project's own guidance forbids for report-derived facts (.mstar/knowledge/best-practices/dsh-upstream-drift-realignment.md:52: "A report-derived fact stays an open question until it is verified, and the docs must say so").
    • Effort: S — re-run/re-record the handshake for those four installs, or relabel/remove the rows.
    • Risk: LOW — documentation only; no behavior changes. Removing a row slightly narrows the advertised compatible set.
    • Confidence: MED — the absence of any record is proven by search; I could not read the upstream release tags (no network) to prove the handshakes never happened.
    • Merge class: may-fix (documentation surface with unverifiable claims; not merge-blocking).
    • Fix sketch: Either record the verification artifacts those rows imply (handshake run + surface diff per tag), or state explicitly that the rows are best-effort reads of the upstream surface rather than handshakes.
  • Location: README.md:63-74
  • Category: DOCS
  • Merge class: may-fix

🔵 Status column in the new table carries no information

  • Evidence:
    • Evidence: README.md:68-75 — every row has the identical Status value verified, while the adjacent prose already defines membership ("Each release below was checked…" / "Releases outside this table are unverified").
    • Impact: One column of repeated noise in both README sides; adds width on narrow viewers and a second place to keep in sync if a status value ever changes.
    • Effort: XS — drop the Status column from both tables.
    • Risk: LOW — cosmetic; the surrounding sentences already carry the same semantics.
    • Confidence: HIGH (opened the table rows).
    • Merge class: nit.
    • Fix sketch: Delete the Status column from the English and Chinese tables; keep Runtime + Verified by.
  • Location: README.md:68-75
  • Category: DOCS
  • Merge class: nit

🟡 PR ships no .changes/unreleased/ fragment although the repo's CI gate requires one

  • Evidence:
    • Evidence: README.zh.md:56-77 — the new ### 已验证的运行时版本 section is a user-facing documentation change; AGENTS.md:36-37 — "Every PR that changes user-visible behavior ships a changelog fragment in the same PR: .changes/unreleased/<slug>.md" and "CI enforces this on PRs"; .github/workflows/ci.yml:146-186 — job changes (name: changelog fragment) runs on every pull_request (no paths-ignore) and exits 1 when git diff --name-only ${BASE}...HEAD -- '.changes/unreleased/' is empty after excluding .gitkeep/README.md. The recon diffstat for this PR is README.i18n.yaml, README.md, README.zh.md only — no fragment.
    • Impact: the changelog fragment check fails mechanically on this PR regardless of the text being correct; the section also introduces no release note for the newly published compatibility promise.
    • Effort: XS
    • Risk: LOW — adding one fragment cannot change crate behavior; only the fragment's category: choice needs judgement (Added vs Changed).
    • Confidence: HIGH (read AGENTS.md, the CI job body, and the PR diffstat).
    • Merge class: may-fix
    • Fix sketch: add .changes/unreleased/<slug>.md (format per docs/release.md) with category: Added or Changed and one English bullet stating that the README pair now publishes the verified-runtime table. Documentation surface — tracked, not a ship-stopper.
  • Location: README.zh.md:56-77
  • Category: docs
  • Merge class: may-fix

🟡 Verified-runtime table claims per-tag audits that the repository cannot substantiate, and drops a previously recorded verification

  • Evidence:
    • Evidence: README.zh.md:58-68 — the section promises every row passed two checks ("下表中的每个版本都经过两项检查") and rows 0.2.1-rc.2…rc.5 each assert 无密钥握手;dsh-v0.2.1-rc.X 的 SDK 表面差异审计. A repo-wide search for 0.2.1-rc.[2345] matches only README.md:71-74 and README.zh.md:65-68. The contract SSOT records re-verification only at two anchors: .mstar/specs/dsh-runtime-launch-contract.md:262 (dsh-v0.2.1-rc.1, 2026-10-17) and :274 (dsh-v0.2.2-rc.1, 2026-11-06); .mstar/specs/dsh-sdk-wire-parity-surface.md:17 likewise only at dsh-v0.2.2-rc.1. .github/workflows/ci.yml:103 pins only @deepseek-ai/[email protected]. CHANGELOG.md:8 records the last npm-route verification against @deepseek-ai/[email protected] — a release the new table omits and therefore now marks "未经验证" per README.zh.md:75-77.
    • Impact: the table is read as a compatibility guarantee (it is the only place telling a consumer which runtime to pin). Four of its six rows have no reproducible evidence in the tree, and one verification the repo itself recorded (0.1.7-rc.1) is silently contradicted by the blanket "releases outside this table are unverified" sentence.
    • Effort: S
    • Risk: LOW — text-only change inside the README pair; the sibling README.md rows and README.i18n.yaml hash must move together (AGENTS.md:42-43).
    • Confidence: MED (absence of in-repo records is strong; the audits may have happened in PR/CI history I cannot read).
    • Merge class: may-fix
    • Fix sketch: keep only rows whose verification is recorded, or add a date + spec/report pointer to each row's 验证方式 cell; reconcile the 0.1.7-rc.1 statement so the pair does not declare a verified release unverified. Documentation surface — register it, do not gate the merge on it.
  • Location: README.zh.md:65-68
  • Category: docs
  • Merge class: may-fix

🔵 Upstream release tags cited as bare strings instead of the official-repo citation the h2 rule requires

  • Evidence:
    • Evidence: README.zh.md:64-69 — every 验证方式 cell cites a bare tag (dsh-v0.2.2-rc.1, dsh-v0.2.1-rc.5, …) with no link; AGENTS.md:45 — "Upstream DSH references only via https://github.com/deepseek-ai/deepseek-harness (citation rule); no local filesystem paths in either README."
    • Impact: a reader cannot follow a row's evidence to the upstream tag, and the pair drifts from the repo's stated citation form (the same cells also name .github/workflows/ci.yml, which is a repo-relative path and therefore in bounds).
    • Effort: XS
    • Risk: LOW — link-only edit; the pair and the recorded blob hashes must be updated together.
    • Confidence: MED (the rule's intent is upstream citations; a bare tag is a judgement call, not a proven breach).
    • Merge class: nit
    • Fix sketch: link each tag to https://github.com/deepseek-ai/deepseek-harness/tree/<tag>, or cite the tag once under the intro paragraph with a single link, keeping EN and ZH rows identical.
  • Location: README.zh.md:64-69
  • Category: docs
  • Merge class: nit
Revalidated findings

Reassessed 0/14 prior finding(s) this round · 14 invalid-output · 0 omitted · 0 over cap · 14 recheckable · context coverage: complete

finding disposition evidence thread
Launch spec §4.2/§5 still cite the frozen-basis sessions-root lines while §10's tag note records the moved location unverifiable (invalid-output) - -
Launch spec §2.2.3 forbids two of the three dump subcommands its own §2.1 enumerates unverifiable (invalid-output) - -
Node floor is stated once, with an unqualified upstream path, and not at the npm route it constrains unverifiable (invalid-output) - -
New CI provenance guard silently no-ops when npm prefix -g yields nothing unverifiable (invalid-output) - -
This changeset trips its own changelog-fragment gate; CI changes job will fail as submitted unverifiable (invalid-output) - -
Rewritten keyless-guard comment is accurate — no claim needs correction (checked, rejected candidate) unverifiable (invalid-output) - -
README divergence inventory omits the newly documented session/prompt vs session/query divergence unverifiable (invalid-output) - -
Launch spec §2.2 carries unmarked frozen-basis line citations next to §2.1's re-anchored ones unverifiable (invalid-output) - -
Knowledge doc still asserts a single upstream pin that both specs have since re-baselined past unverifiable (invalid-output) - -
Partial re-baseline leaves dsh-v0.2.1-rc.1 anchors in the same doc comments the PR re-tagged unverifiable (invalid-output) - -
Docs/CI-comment change ships with no .changes/unreleased fragment, so the changelog fragment job fails on this PR unverifiable (invalid-output) - -
git diff ... || true can turn a diff-computation failure into the release-prep exemption unverifiable (invalid-output) - -
The two normative specs cite different upstream lines for Python's initialize_timeout_seconds on the same re-baseline unverifiable (invalid-output) - -
Wire spec §2's method inventory and its §9 assertion disagree about which methods exist unverifiable (invalid-output) - -

Linked-issue AC

none

✅ Verified

none

🗑️ Considered & rejected

none

🛠️ Plan to fix

none

Review 3 · commit d2e0dc1 · since 7a5e189

@wood-s-inspector wood-s-inspector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mstar-inspector line comments · round 1 · f90f197

Comment thread .github/workflows/ci.yml Resolved
Comment thread README.md Resolved

@wood-s-inspector wood-s-inspector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mstar-inspector line comments · round 2 · 7a5e189

Comment thread .github/workflows/ci.yml Resolved
The READMEs named no runtime version at all, leaving readers to guess which
@deepseek-ai/dsh releases the crate was checked against. Add one section, right
after the Node-floor prerequisites, listing 0.2.1-rc.1..rc.5 and 0.2.2-rc.1
with the check each one passed: keyless handshake (crate boots the runtime,
initialize completes, close reaps the child) plus a reading of the upstream
SDK-facing surface at the release tag. Each row is a fact with its method; the
six-method, unknown-tolerant wire contract explains why additive upstream
changes pass through, and versions outside the table are marked unverified.

Re-record README.i18n.yaml with the new blob hashes.

@wood-s-inspector wood-s-inspector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mstar-inspector line comments · round 3 · d2e0dc1

Comment thread README.md Resolved
Comment thread README.md Resolved
Comment thread README.md Resolved
Comment thread README.zh.md Resolved
Comment thread README.zh.md Resolved
Comment thread README.zh.md Resolved
@btspoony
btspoony merged commit a845544 into main Nov 6, 2026
7 checks passed
@btspoony
btspoony deleted the upgrade/13-dsh-0.2.2-rc1-adaptation branch November 6, 2026 06:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant